Input Reference
Table of contents
- Introduction
- Action
- Any
- Joy Axis 1D
- Joy Axis 2D
- Joy Button
- Key
- Mouse Axis 1D
- Mouse Axis 2D
- Mouse Button
- Mouse Position
- Touch Angle
- Touch Axis 1D
- Touch Axis 2D
- Touch Distance
- Touch Position
Introduction
G.U.I.D.E ships with a selection of inputs for all kinds of input devices. This is a list of all built-in inputs and their settings:
Action
This input takes a GUIDEAction
and returns the current value of the action. This way you can use an action value as input for another action. The input will actively track the state of the action and update the value accordingly. This means the input works independently of whether the action is currently bound to an active mapping context and it also works independently of the order in which the action in bound in a mapping context. This input will always mirror the full Vector3 of the action value (even if the action only uses parts of it). The input has the following settings:
Setting | Description |
---|---|
Action | The action that the input should track. |
Any
This input returns (1,0,0)
if any input of the selected types is received, and (0,0,0)
otherwise. This is useful to switch input schemes when you detect controller input from a certain device (e.g. switch to a controller or touch input scheme when receiving controller or touch input). Can also be used to realize things like “press any key to continue”. The input has the following settings:
Setting | Description |
---|---|
Mouse Buttons | Detect input from mouse buttons. |
Mouse Motion | Detect mouse motion. |
Joy Buttons | Detect input from joystick / joypad buttons. |
Joy Axes | Detect input from joystick / joypad axes. |
Keyboard | Detect input from the keyboard |
Touch | Detect touch input |
Joy Axis 1D
This input returns the value of a 1D axis of a joystick in the x
component of the input value. The input is restricted to the range of (-1, 0, 0)
to (1, 0, 0)
, while usually being (0,0,0)
when the axis is not actuated. Note that some joy axes only use positive values (e.g. controller triggers). The input has the following settings:
Setting | Description |
---|---|
Axis | The joy axis that should be tracked by the input. |
Joy Axis 2D
This input returns the value of a 2D axis of a joystick in the x
and y
components of the input value. The input is restricted to the range of (-1, -1, 0)
to (1, 1, 0)
, while usually being (0,0,0)
when the axis is not actuated. The input has the following settings:
Setting | Description |
---|---|
X | The joy axis that should be tracked by the input for the x component. |
Y | The joy axis that should be tracked by the input for the y component. |
Joy Button
This input returns (1,0,0)
if the selected joystick button is pressed, and (0,0,0)
otherwise. The input has the following settings:
Setting | Description |
---|---|
Button | The joy button that should be tracked by the input. |
Key
This input returns (1,0,0)
if the selected key is pressed, and (0,0,0)
otherwise. If modifiers are given, then both the key and all selected modifiers must be pressed in order for this input to return the actuated value of (1,0,0)
. The input has the following settings:
Setting | Description |
---|---|
Key | The key that should be tracked by the input. This is expected to be a physical key code, so that the physical location of the key in the keyboard stays the same no matter which locale the keyboard is operating in. |
Shift | Whether the Shift modifier key must be pressed in addition to the main key. |
Control | Whether the Ctrl modifier key must be pressed in adition to the main key. |
Alt | Whether the Alt modifier key must be pressed in addition to the main key. |
Meta | Whether the Meta modifier key (Windows key on Windows, Cmd on OSX) must be pressed in addition to the main key. |
Allow additional modifiers | If true, the key input will actuate if modifiers in additional to the enabled ones are pressed. Let’s assume you set up the key to D and disable Shift, Control, Alt and Meta and also disable Allow additional modifiers. Now the input will only actuate while the D key is pressed alone, but will not actuate when any modifier key is pressed in addition to D . Usually this is not what you want, so Allow additional modifiers is true by default. |
Mouse Axis 1D
This input returns changes in mouse position along a single axis in the x
component of the input value (e.g. (x, 0, 0)
). The input is given in pixels per frame. You can use a Screen Relative modifier to convert this into a value from -1 to 1 that is independent of the screen resolution. The input has the following settings:
Setting | Description |
---|---|
Axis | The mouse axis that should be tracked by the input. |
Mouse Axis 2D
This input returns changes in mouse position compared to the previous frame along two axes in the x
and y
components of the input value (e.g. (x, y, 0)
). This is useful for first-person shooter mouse aiming. On most systems this value is given in raw mouse units, so it is resolution independent. Depending on the underlying operating system and whether the mouse cursor is currently visible, you may get viewport pixels. You can use the Screen Relative modifier to convert the value to be resolution independent in this case.
Mouse Button
This input returns (1,0,0)
if the selected mouse button is pressed, and (0,0,0)
otherwise. Note, that Godot also treats the mouse wheel as buttons. If you need an axis from the wheel, you can
map Wheel Up + a Negate Modifier and Wheel Down to a 1-dimensional action. The input has the following settings:
Setting | Description |
---|---|
Button | The mouse button that should be tracked by the input. |
Mouse Position
This input returns the current mouse position in pixels relative to the top left corner of the window in the x
and y
components of the input value (e.g. (x, y, 0)
). You an use a Canvas Coordinates modifier to convert this into a value into 2D world coordinates for the currently active viewport or a 3D Coordinates modifier to convert this into 3D world coordinates (e.g. for object picking). This input has no settings.
Touch Angle
This input tracks changes in the angle between two touching fingers. This is mostly useful to detect rotation gestures. When the user touches the screen with two fingers the input will return (0,0,0)
. If the user subsequently performs a rotation gesture, the input will return the angle changes since the beginning of the touch (e.g. (<angle>,0,0)
). Once the user releases the touch, the input will return to (0,0,0)
. Note that when you use this input to rotate elements, that the input will retain the angle for as long as the fingers are touched. You should therefore save the starting rotation angle when the rotation begins and then apply the angle from the input on the starting value to show the user a preview of the rotation. Once the rotation ends, you can commit the value. This input has the following settings:
Setting | Description |
---|---|
Unit | The unit in which the angle is reported (degrees or radians). |
Touch Axis 1D
This input treats touch input like an axis, similar to the Mouse Axis 1D input. When the user begins to touch the screen, and then drags, this input will return the delta value in pixels compared to the previous frame. You can use a Screen Relative modifier to convert this into a value from -1 to 1 that is independent of the screen resolution. The value is returned in the x
component of the input vector (e.g. (<value>, 0, 0)
). If the user does not touch the screen this will return (0, 0, 0)
. This input has the following settings:
Setting | Description |
---|---|
Axis | The axis that should be tracked by the input (X or Y). |
Finger Count | The amount of fingers that must be on the screen for this input to react. The finger count must match exactly (e.g. if finger count is 2 then this input will only react while exactly 2 fingers are placed). |
Finger Index | The position of which finger should be used for calculating the offset. Use 0 for the first finger, 1 for the second, and so on. You can also use -1 which will use the average position of all active fingers. |
Touch Axis 2D
Similar to Touch Axis 1D but returns input returns changes in touch position along two axes in the x
and y
components of the input value (e.g. (x, y, 0)
). The input is given in pixels relative to the previous frame. You can use a Screen Relative modifier to convert this into a value from -1 to 1 that is independent of the screen resolution. This input has the following settings:
Setting | Description |
---|---|
Finger Count | The amount of fingers that must be on the screen for this input to react. The finger count must match exactly (e.g. if finger count is 2 then this input will only react while exactly 2 fingers are placed). |
Finger Index | The position of which finger should be used for calculating the offset. Use 0 for the first finger, 1 for the second, and so on. You can also use -1 which will use the average position of all active fingers. |
Touch Distance
This input will track distance changes between two fingers. This is mostly useful to detect pinch/zoom gestures. When the user touches the screen with two fingers the input will return (1,0,0)
. If the user subsequently performs a pinch or zoom gesture, the input will return a ratio of the current finger distance compared to the distance at the beginning of the touch (e.g. (<distance ratio>, 0 ,0)
). At the beginning, this ratio is 1
. If the user makes a pinch gesture, the ratio become smaller, e.g. if the fingers distance is halved, the ratio will be 0.5
. If the user performs a zoom gesture, the ratio will grow, e.g. if the finger distance is doubled, the ratio will be 2.0
. Once the user releases the touch, the input will return to (0,0,0)
.
Like with the Touch Angle input, the input will retain the ratio for as long as the fingers are touched. You should therefore save the starting zoom/scale when the distance change begins and then apply the ratio from the input on the starting value to show the user a preview of the scale. Once the distance change ends, you can commit the value. This input has no settings.
Touch Position
This input returns the current position of a touching finger in pixels relative to the top left corner of the screen in the x
and y
components of the input value (e.g. (x, y, 0)
). You an use a Canvas Coordinates modifier to convert this into a value into 2D world coordinates for the currently active viewport or a 3D Coordinates modifier to convert this into 3D world coordinates (e.g. for object picking). If no finger is currently touching or the amount of touching fingers does not match Finger Count, the input is (INF, INF, INF)
. You can use Godot’s is_finite()
method to check if the input is currently valid. G.U.I.D.E’s triggers will treat this value as “not actuated”. This input has the following settings:
Setting | Description |
---|---|
Finger Count | The amount of fingers that must be on the screen for this input to react. The finger count must match exactly (e.g. if finger count is 2 then this input will only react while exactly 2 fingers are placed). |
Finger Index | The position of which finger should be reported. Use 0 for the first finger, 1 for the second, and so on. You can also use -1 which will use the average position of all active fingers. |